fix(backends): honor inherited model label + warn on engine/model incompatibility - #1533

Summary

Fixes MNG-1772. The agent detail panel's Model picker showed a fictional fallback (Default (Sonnet 5)) that the runtime never applies. The runtime chain (src/agents/shared/modelResolution.ts) is override → per-agent → project.model with no engine-default step, so an empty override actually inherits project.model — which defaults to openrouter:google/gemini-3-flash-preview and then fails the claude-code engine guard mid-run. This PR makes the UI honest and surfaces the incompatibility at configuration time.

What changed

1. Honor defaultLabel on the ModelField select branch (web/src/components/settings/model-field.tsx)

• New exported pure helper resolveSelectEmptyLabel(defaultLabel, engineDefaultValueLabel) → defaultLabel ?? engineDefaultValueLabel.
• The empty (_none) option now renders the caller's inheritance-aware label (Inherit from project (X)) instead of the engine catalog's hardcoded default — matching the agents list. The _none → '' save mapping is unchanged.

2. Derive defaultValueLabel from the default-model constants (src/backends/catalog.ts, claude-code/models.ts, codex/models.ts)

• New helper defaultModelLabel(models, defaultId) → Default (${label ?? id}).
• Replaced the hardcoded 'Default (Sonnet 5)' / 'Default (GPT-5.4)' literals with values derived from DEFAULT_CLAUDE_CODE_MODEL / DEFAULT_CODEX_MODEL + catalog lookup, killing the hand-sync drift class.

3. Normalize the project harness-form model default label (web/src/components/projects/project-harness-form.tsx)

• Project-level Model field now passes Default (${defaults.model}) for a clear empty-option read.

4. Config-time engine/model incompatibility warning (src/backends/*, web/src/components/projects/*)

• Single-sourced the runtime acceptance rules as CLAUDE_CODE_ACCEPTED_PREFIXES = ['claude-', 'anthropic:'] / CODEX_ACCEPTED_PREFIXES = ['openai:'] next to the model lists, consumed by resolveClaudeModel / resolveCodexModel (no behavior change).
• Exposed them on the serializable engine definition as modelSelection.acceptedModelPrefixes?: readonly string[] (plain array — serializes across the agentConfigs.engines tRPC query).
• New pure FE helper isModelCompatibleWithEngine(model, engine) (catalog-membership OR accepted-prefix match; free-text/unknown engines always compatible).
• The agent-config detail panel computes the effective engine (agentEngine || inheritedEngine) + effective model (model || inheritedModel) and shows an inline amber AlertTriangle warning when a select-type engine would fail on the inherited model. Turns a post-dispatch crash into a config-time signal.

5. Tests

• resolveSelectEmptyLabel, isModelCompatibleWithEngine, defaultModelLabel unit tests.
• Anti-drift guard in tests/unit/backends/catalog.test.ts asserting displayed default == resolved default for every select engine — fails loudly on the next model bump.
• Existing resolveClaudeModel / resolveCodexModel tests remain green (refactor is behavior-preserving).

6. Docs — docs/adding-engines.md modelSelection example now derives defaultValueLabel from the default-model constant and documents the new optional acceptedModelPrefixes.

Scope notes

• Intentionally does not add an engine-default step to modelResolution.ts (that is the direction-4 product decision). This PR makes the UI honest about the existing chain.
• The deeper PROJECT_DEFAULTS claude-code + openrouter default mismatch is flagged by the new warning rather than silently changed — a follow-up product call.
• No DB / migration / runtime-dispatch changes: purely presentational plus a shared read-only predicate and a behavior-preserving refactor.

Testing

• npm run typecheck (root) + tsc -b (web) — clean
• biome check on changed files — clean
• npx vitest run for catalog.test.ts, model-field.test.ts, agent-config-utils.test.ts, claude-code.test.ts, codex.test.ts, engine-contract, registry, resolution, all tests/unit/web/, and architecture-docs.test.ts — all passing

🤖 Generated with Claude Code

🕵️ claude-code · claude-opus-4-8 · run details